home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Graphics Plus
/
Graphics Plus.iso
/
msdos
/
presnttn
/
pic_tc
/
pic_read.me
< prev
next >
Wrap
Text File
|
1990-05-31
|
42KB
|
1,980 lines
Welcome to PIC_TC (Version 1.10)
PIC_TC
"a PIC library for Turbo C"
by
Dennis F. Lovely
Version 1.10, June 1990
(c) copyright 1990 by CSH Services
LICENCING AND SHAREWARE POLICY
This version of PIC_TC is being distributed under the 'ShareWare'
concept. The 'ShareWare' concept is based on three principles:
1. People need to try programs to see if they are useful.
2. Software authors can be supported directly by users.
3. Copying and networking of programs can be encouraged.
Only by supporting the program authors who release valuable
programs as 'ShareWare' can you encourage others to do the same.
The bottom line is - if you're still using a user supported
program after a couple of weeks, then it's pretty obvious that it's
worth something to you, and you should send in a contribution.
If user supported software works, then everyone will benefit. The
user will benefit by receiving quality products at low cost, and
by being able to "test drive" software thoroughly before
purchasing it. The author benefits by being able to enter the
commercial software arena without first needing large sources of
venture capital.
Why choose this route?
Because of cost. As an individual, I cannot even come close to
meeting the costs of marketing commercial software. Here is what
I'm asking:
If you like this program, and find it of use, then your registration
($25 US / $30 CDN) will be greatly appreciated and used in supporting
future, improved versions. Plus, I will mail you the next update as
soon as it is ready, at no additional charge. A program disk, includ-
ing all source code and laser printed documentation is available for
$45 US / $54 CDN, plus you still get the next update, again at no
additional charge.
ii
What do you get for your registration?
1) the next major version will be sent to you, at no additional
charge. After that, you can always get the current version
for a distribution charge of $10.
2) you encourage me to keep improving and adding features to the
PIC_TC library.
3) if you wish, you'll get on my mailing list for announcements
of future versions and/or products.
4) you'll get support. I do not have the time to support non-
registered users, but I will always make time to support
registered users.
What can you do with your copy of PIC_TC?
Actually, just about anything you want to! Remember that PIC_TC is the
copyrighted property of CSH Services. Beyond that, I would appreciate
if you would:
1) Copy and freely distribute it, as long as NO fee is charged
for such copying and distribution and it is distributed ONLY
in its original, unmodified form.
2) Please, don't rip me off! If you'd like to distribute PIC_TC
embedded in your own software for commercial gain, then
please become a registered user.
3) If you are using this program in a commercial or educational
environment, then I really think that you should register your
copy. That way I'll stay in business and you'll be sure to get
support!
I really would like to hear your comments about PIC_TC. Even if
you're not a registered user, feel free to let me know what you
think about it. If it really stinks, then tell me about it, and
be sure to let me know where it might be improved! With your
comments, hopefully I can produce a better product.
I can be reached at:
Tel: (506) 453-4966
Fax: (506) 452-1040
during the hours of 1:00 p.m. to 3:00 p.m. EST, Monday through Friday.
Please do NOT call at other times. Sorry, but I cannot accept collect
calls.
iii
Make all cheques payable to CSH Services. Please - to help me
forward updates to you, include your PRINTED name and address.
If at all possible, please fill out the enclosed order form shown
below.
____________________________________________________________________
ORDER FORM
(please indicate the required product and disk format)
Product:
a) PIC_TC Registration : $ 25 / $ 30 CDN
b) PIC_TC Source code + manual : $ 45 / $ 54 CDN
Disk format (if applicable):
c) 5 1/4" 360 kbyte d) 3 1/2" 720 kbyte
Ship to:
Name ......................................................
Address ...................................................
City ................... State/Province ...................
Zip/PC ................. Country...........................
____________________________________________________________________
Please send completed order form with your payment (US or Canadian
funds) to :
CSH Services
Comp. 149 Site 14 SS#3
FREDERICTON
New Brunswick
CANADA, E3B 5W9
Please allow 21 days for delivery.
PIC_TC
"a PIC library for Turbo C"
by
Dennis F. Lovely
Version 1.10, June 1990
(c) copyright 1990 by CSH Services
REFERENCE MANUAL
Disclaimer
CSH Services makes no representation or warranties with respect to
the contents hereof and specifically disclaims any implied warranties
to the suitability of this program for any particular purpose.
You must determine that yourself. In addition, you should
understand that using a program of this type on an IBM PC or
compatible has inherent risks and that you may inadvertently
damage or destroy valuable programs or data. CSH Services expressly
declines to assume liability for any use of this program by you,
and your use of this program constitutes your agreement to hold us
blameless. CSH Services reserves the right to make changes from time
to time in the context hereof without obligation to notify any
person or persons of such changes.
Trademarks
MS-DOS is a registered trademark of Microsoft Corporation.
PC-DOS is a registered trademark of IBM Corporation.
TURBO C is a registered trademark of Borland International Inc.
PIC is a registered trademark of Lotus Development Corp.
HPGL is a registered trademark of Hewlett-Packard.
- 2 -
TABLE OF CONTENTS
Acknowledgements 3
1. INTRODUCTION ......................................... 4
2. FEATURES OF PIC_TC ................................... 5
3. SYSTEM REQUIREMENTS .................................. 6
4. FILES INCLUDED WITH PIC_TC ........................... 7
5. RUNNING THE DEMONSTRATION ............................ 8
6. QUICK REFERENCE ...................................... 9
7. COMMAND REFERENCE ................................... 10
8. FUTURE UPDATES ...................................... 28
- 3 -
Acknowledgments
Many months of work went into the development of PIC_TC, with several
people contributing in their own way. Consequently, special thanks
go to:
* Tomasz W. Hruczkowski, for his endeavours through the E-mail
system and file encoding for uploading this software.
* My wife, for putting up with all the long hours, in the basement
slaving over a hot computer, developing this package.
* To ALL registered users - THANK YOU - it is only through your
support that additional versions are made possible.
- 4 -
1. INTRODUCTION
This manual describes the use and operation of PIC_TC, a library
of routines, callable from any Turbo C program, to produce graphics
in the LOTUS PIC file format. This is especially useful for
incorporating wordprocessor compatibility into your own graphic
programs.
The manual includes setup instructions, description of a demonstration
program (included with this package), and full reference for all of
the available functions in PIC_TC.
All the functions of PIC_TC are contained in each of five different
object files for Small, Medium, Compact, Large and Huge memory model
environments. It is up to the user to select the appropriate object
file for his/her application.
Providing the user is registered, there is no additional licencing
charge to incorporate these routines into commercial software under
development.
- 5 -
2. FEATURES OF PIC_TC
The PIC_TC library contains all the basic instructions applicable
to the PIC file format. These include the primitive "pen up draw"
and "pen down draw" along with font and colour selection. In
addition, CSH Services have included useful features such as relative
drawing, scaling, rectangle drawing and block rectangle functions.
In all, 17 user callable functions have been provided in PIC_TC
Version 1.10 to enable the user to create graphics in the PIC file
format. The format of these functions is listed briefly in
Section 6: Quick Reference, while full descriptions and examples are
given in Section 7: Command Reference.
All of the functions return error codes which allow the user to
verify that the particular operation was completed sucessfully.
NOTE: The PIC_TC library does not allow the user to view PIC
files, whether created by the library or from 3rd party
software. To view PIC files suitable additional software
is required.
- 6 -
3. SYSTEM REQUIREMENTS
The PIC_TC library does require that the user has a copy of TURBO C
from Borland International Inc. It is also expected that the user
has a working knowledge of the C programming language.
The PIC_TC library can be used on any machine running PC-DOS or
MS-DOS with enough memory to support the TURBO C integrated
environment.
No graphics card is necessary to use the software, however if the
final image is to be viewed, rather than printed, then a graphics
card is of course mandatory.
- 7 -
4. FILES INCLUDED WITH PIC_TC
There are 10 files associated with the PIC_TC library. These are
listed below:
PIC_TC_S.OBJ - Small memory model
PIC_TC_M.OBJ - Medium memory model
PIC_TC_C.OBJ - Compact memory model
PIC_TC_L.OBJ - Large memory model
PIC_TC_H.OBJ - Huge memory model
PIC_TC.H - Prototype definitions of PIC functions
DEMOPIC.EXE - Demonstration program (ready to run)
DEMOPIC.C - Demonstration program (source)
DEMOPIC.PRJ - Demonstration program (project make file)
PIC_READ.ME - This document
NOTE: It is your responsibility to make backup copies of the
program disk we send you. Never use your program disk
without making such a backup copy.
- 8 -
5. RUNNING THE DEMONSTRATION
A well commented demonstration program (DEMOPIC.C) is included
with the library of routines to illustrate the use of the individual
functions. This program will produce a PIC file called TRY.PIC
which can be imported into LOTUS 123 or other commercial software
packages to be viewed or printed.
The user should first of all examine the source code to see how the
library is used. In all applications the prototype definition file
(PIC_TC.H) should be included at the top of any source code which
calls the routines. A project make file is also included which
specifies that the SMALL memory model object code should be linked
with the demonstration program.
The user should first bring up TURBO C in the interactive mode using
the TC command. The compiler options should be set to a SMALL memory
model and the project make file (DEMOPIC.PRJ) specified. The
demonstration program source code (DEMOPIC.C) should be accessible
to the compiler and the program built to create an executable file
called (DEMOPIC.EXE).
The user can either leave the TURBO C environment and run the
demonstration from the DOS prompt, or run the demonstration directly
using the 'Ctrl R' key combination from the TURBO C integrated
environment. In either case, a brief description of the demonstration
will be given and the user asked whether to continue or not.
Continuation will result in the creation of a file in PIC format
(TRY.PIC) which illustrates all of the functions of the TC_PIC library.
This file can be viewed by several means. Firstly, using any software
product which permits the importation of a PIC graphic file,
eg. Lotus 123, Freelance etc. The second method of viewing the image
is to use a wordprocessor which can accept PIC file formats,
eg. Manuscript etc.
The circles at the left hand side of the image are in different
colours. The rectangular solid area to the right is in fact a series
of square blocks of different colour with the colour numbers shown to
the left of the blocks. The majority of the text is in font style #1
with the exception of the copywrite notice which is in font style #2.
Using Lotus 123 the appearance of this image can be changed to
illustrate the colours used and the different font styles. With
Manuscript, and some other wordprocessors, these options are not
available consequently the appearance is limited to monochrome and
a single font style.
- 9 -
6. QUICK REFERENCE
This section is intended to be used as a quick reference to all the
functions included in PIC_TC Version 1.10. This page should be
photocopied and kept at hand during program development until one
gets familiar with the functions.
OPENING & CLOSING PIC FILE
pic_open(char *filepath) opens PIC file & initialises
pic_close(void) terminates plot & closes file
PRIMITIVES
pic_pu_move_abs(float x,float y) absolute move with pen up
pic_pu_move_rel(float x,float y) relative move with pen up
pic_pd_move_abs(float x,float y) absoulte move with pen down
pic_pd_move_rel(float x,float y) relative move with pen down
GENERAL DRAWING ATTRIBUTES
pic_set_colour(int col) set drawing colour
pic_set_font(int type) set character font
pic_set_linetype(int type) set line type
GENERAL DRAWING SCALING
pic_set_cs(float x,float y) set character size
pic_set_sp(int x1,int y1, set scaling points
int x2,int y2)
pic_set_scale(float xmin,float xmax, set drawing scale
float ymin,float ymax)
DRAWING COMMANDS
pic_draw_rectangle(float x1,float y1, draw rectangle
float x2,float y2)
pic_draw_line(float x1,float y1, draw line
float x2,float y2)
pic_draw_block(float x1,float y1, draw filled rectangle
float x2,float y2)
pic_draw_circle(float x1,float y1, draw circle
float r)
pic_draw_text(char *text,int r, write text string
int j)
- 10 -
7. COMMAND REFERENCE
pic_open
PURPOSE: Opens and initializes a binary file in Lotus PIC
format
SYNTAX: int pic_open(char *filepath);
EXAMPLE CALL: if(pic_open("c:\path\filename.pic")!=0){
printf("ERROR IN OPENING FILE");
return(0);
}
.
.
DESCRIPTION: Creates a binary file named by the user and writes
the PIC file header and initialization bytes. It is
advised that the user employ the .PIC extension to
be compatible with other 3rd party software.
RETURNS: The pic_open function returns 0 if a file was correctly
opened. If an error occurred a code indicating the
type of error is returned. Possible error codes are:
1 - error in opening file
2 - file write error
- 11 -
pic_close
PURPOSE: Closes a PIC file previously opened using pic_open
SYNTAX: int pic_close(void);
EXAMPLE CALL: if(pic_close()!=0){
printf("ERROR IN CLOSING FILE");
return(0);
}
.
.
DESCRIPTION: Writes the termination code to the end of a PIC file
and closes the file.
RETURNS: The pic_close function returns 0 if a file was correctly
closed. If an error occurred a code indicating the
type of error is returned. Possible error codes are:
2 - file write error
3 - error in closing file
- 12 -
pic_set_colour
PURPOSE: Sets the current drawing colour
SYNTAX: int pic_set_colour(int colour);
EXAMPLE CALL: int err;
.
.
err=pic_set_colour(2);
.
.
DESCRIPTION: Determines the current drawing colour for subsequent
draw commands. Valid colour numbers are from 1 to 8
inclusive.
RETURNS: The pic_set_colour function returns 0 if a valid colour
code was specified. If an error occurred a code
indicating the type of error is returned. Possible
error codes are:
2 - file write error
7 - invalid colour code
- 13 -
pic_set_font
PURPOSE: Sets the current font style
SYNTAX: int pic_set_font(int font);
EXAMPLE CALL: int err;
.
.
err=pic_set_font(3)
.
.
DESCRIPTION: Determines the font style to be used with subsequent
text string output. Valid font numbers are from 1
to 8 inclusive.
RETURNS: The pic_set_font function returns 0 if a valid font
number was selected. If an error occurred a code
indicating the type of error is returned. Possible
error codes are:
2 - file write error
6 - invalid font number
- 14 -
pic_set_linetype
PURPOSE: Sets the current line type
SYNTAX: int pic_set_linetype(int linetype);
EXAMPLE CALL: int err;
.
.
err=pic_set_linetype(3);
.
.
DESCRIPTION: Determines the current line type for subsequent draw
commands. Valid line type numbers are from 0 to 4
inclusive. The appearance of these line types are as
follows:
0 - solid line
1 - broken line (line:space ratio = 1:1)
2 - broken line (line:space ratio = 1:2)
3 - broken line (line:space ratio = 1:3)
4 - dotted line
NOTE: The scale of the line type is fixed at 2.5% of the
distance between the scaling points and is consequently
affected by scaling point changes (see pic_set_sp).
RETURNS: The pic_set_linetype function returns 0 if a valid line
type code was specified. If an error occurred a code
indicating the type of error is returned. Possible
error codes are:
2 - file write error
8 - invalid line type code
- 15 -
pic_set_cs
PURPOSE: Sets the character size for text output
SYNTAX: int pic_set_cs(float width,float height);
EXAMPLE CALL: int err;
.
.
err=pic_set_cs(0.1,0.2)
.
.
DESCRIPTION: Determines the size of text characters output by the
pic_write_text command, with independent control of
height and width.
NOTE: The character size is specified in the same units
as all the other drawing commands and is consequently
affected by scale changes (see pic_set_scale).
RETURNS: The pic_set_cs function returns 0 if the command was
sucessfully writen to the PIC file. If an error
occurred a code indicating the type of error is
returned. Possible error codes are:
2 - file write error
- 16 -
pic_set_sp
PURPOSE: Sets the scaling points for drawing commands
SYNTAX: int pic_set_sp(int x1,int y1,int x2,int y2);
EXAMPLE CALL: int err;
.
.
err=pic_set_sp(100,200,2100,2200);
.
.
DESCRIPTION: Determines the extents of the drawing with respect to
the absolute coordinates of the PIC file format. The
largest allowed drawing has the lower corner at (0,0)
and the upper right hand corner at (3180,2300).
NOTE: Programmers who are familiar with the
Hewlett-Packard Graphics Language (HPGL) will find this
function is equivalent to the SP command.
RETURNS: The pic_set_sp function returns 0 if valid scaling
points were specified. If an error occurred a code
indicating the type of error is returned. Possible
error codes are:
2 - file write error
4 - scaling points out of valid range
- 17 -
pic_set_scale
PURPOSE: Re-maps the PIC file coordinates into user coordinates
SYNTAX: int pic_set_scale(float xmin,float xmax,
float ymin,float ymax);
EXAMPLE CALL: int err;
.
.
err=pic_set_scale(-10.0,10.0,-10.0,10.0)
.
.
DESCRIPTION: Maps the distance between the scaling points to a user
defined coordinate system. Subsequent draw commands
will use this new coordinate system. This allows the
user to employ more convenient units when creating a
PIC file.
RETURNS: The pic_set_scale function returns 0 if valid scale was
specified. If an error occurred a code indicating the
type of error is returned. Possible error codes are:
2 - file write error
5 - scaling factor error
- 18 -
pic_pu_move_abs
PURPOSE: Moves with the 'pen up' to the point x,y
SYNTAX: int pic_pu_move_abs(float x,float y);
EXAMPLE CALL: int err;
.
.
err=pic_pu_move_abs(8.3,-4.6);
.
.
DESCRIPTION: Moves the current location of the 'pen' without drawing
any lines. The units are as defined by the user via
the pic_set_scale command.
RETURNS: The pic_pu_move_abs function returns 0 if the
appropriate commands were written to the opened PIC
file. If an error occurred a code indicating the type
of error is returned. Possible error codes are:
2 - file write error
- 19 -
pic_pu_move_rel
PURPOSE: Moves with the 'pen up' relative to the last point
SYNTAX: int pic_pu_move_rel(float x,float y);
EXAMPLE CALL: int err;
float width,height;
.
.
pic_set_cs(width,height);
pic_pu_move_abs(5,5);
pic_write_text("line 1",0,0);
err=pic_pu_move_rel(0,-height);
pic_write_text("line 2",0,0);
.
.
DESCRIPTION: Moves the current location of the pen, relative the
previous location, without drawing any lines. The
units are as defined by the user via the pic_set_scale
command.
NOTE: This command is useful for aligning text in
columns (see example above).
RETURN: The pic_pu_move_rel function returns 0 if the
appropriate commands were written to the opened PIC
file. If an error occurred a code indicating the type
of error is returned. Possible error codes are:
2 - file write error
- 20 -
pic_pd_move_abs
PURPOSE: Moves with the 'pen down' to the point x,y
SYNTAX: int pic_pd_move_abs(float x,float y);
EXAMPLE CALL: int err;
.
.
err=pic_pd_move_abs(8.3,-4.6);
.
.
DESCRIPTION: Moves the current location of the 'pen' drawing a line
between the previous location and the new location.
The units are as defined by the user via the
pic_set_scale command.
RETURN: The pic_pd_move_abs function returns 0 if the
appropriate commands were written to the opened PIC
file. If an error occurred a code indicating the type
of error is returned. Possible error codes are:
2 - file write error
- 21 -
pic_pd_move_rel
PURPOSE: Moves with the 'pen down' relative to the last point
SYNTAX: int pic_pd_move_rel(float x,float y);
EXAMPLE CALL: int err;
float i,ticklength;
.
.
pic_pu_move_abs(-5.0,0);
for(i=-5.0;i<=5.0;i++){
pic_pd_move_abs(i,0);
err=pic_pd_move_rel(0,-ticklength);
pic_pu_move_rel(0,ticklength);
}
.
.
DESCRIPTION: Moves the current location of the pen, relative the
previous location, with the pen down. The units are
as defined by the user via the pic_set_scale command.
NOTE: This command is useful for drawing tick marks
on a graph axis (see example above).
RETURN: The pic_pd_move_rel function returns 0 if the
appropriate commands were written to the opened PIC
file. If an error occurred a code indicating the type
of error is returned. Possible error codes are:
2 - file write error
- 22 -
pic_draw_rectangle
PURPOSE: Draws a rectangle
SYNTAX: int pic_draw_rectangle(float x1,float y1,
float x2,float y2);
EXAMPLE CALL: int err;
.
.
err=pic_draw_rectangle(-3.5,-3.5,3.5,3.5);
.
.
DESCRIPTION: Draws a rectangle with the lower left and upper right
corners specified in user units. After successful
execution of the command, the current pen location is
unchanged.
RETURN: The pic_draw_rectangle function returns 0 if the
appropriate commands were written to the opened PIC
file. If an error occurred a code indicating the type
of error is returned. Possible error codes are:
2 - file write error
- 23 -
pic_draw_line
PURPOSE: Draws a line
SYNTAX: int pic_draw_line(float x1,float y1,float x2,float y2);
EXAMPLE CALL: int err;
.
.
err=pic_draw_line(-3.5,-3.5,3.5,3.5);
.
.
DESCRIPTION: Draws a line with the end points specified in user
units. After successful execution of the command, the
current pen location is unchanged.
RETURN: The pic_draw_line function returns 0 if the
appropriate commands were written to the opened PIC
file. If an error occurred a code indicating the type
of error is returned. Possible error codes are:
2 - file write error
- 24 -
pic_draw_block
PURPOSE: Draws a solid filled rectangle
SYNTAX: int pic_draw_block(float x1,float y1,float x2,float y2);
EXAMPLE CALL: int err;
.
.
err=pic_draw_block(-3.5,-3.5,3.5,3.5);
.
.
DESCRIPTION: Draws a rectangle with the lower left and upper right
corners specified in user units and fills the rectangle
with the current selected colour (see pic_set_colour).
After successful execution of the command, the current
pen location is unchanged.
RETURN: The pic_draw_block function returns 0 if the
appropriate commands were written to the opened PIC
file. If an error occurred a code indicating the type
of error is returned. Possible error codes are:
2 - file write error
- 25 -
pic_draw_circle
PURPOSE: Draws a circle
SYNTAX: int pic_draw_circle(float x,float y,float radius);
EXAMPLE CALL: int err;
.
.
err=pic_draw_circle(0,0,3.5);
.
.
DESCRIPTION: Draws a circle centred on the specified user
coordinates with a given radius. After successful
execution of the command, the current pen location
is set to the centre of the circle. In Version 1.1
the circle is drawn in a solid line type (ie. type 0).
RETURN: The pic_draw_circle function returns 0 if the
appropriate commands were written to the opened PIC
file. If an error occurred a code indicating the type
of error is returned. Possible error codes are:
2 - file write error
11- invalid radius specified
- 26 -
pic_draw_text
PURPOSE: Writes a text string at the current pen location
SYNTAX: int pic_draw_text(char *textstring,int rotation,
int justify);
EXAMPLE CALL: int err;
.
.
err=pic_draw_text("Hello world",0,1);
.
.
DESCRIPTION: Writes a text string at the current pen location using
the current font and character size. The angle of the
text can be specified along with the justification with
respect to the current pen location.
The 'rotation' argument can take values from 0 to 3
inclusive. This argument controls the angle the text
makes with the horizontal. The convention adopted is
shown below:
0 - 0[degree] - left to right
1 - 90[degree] CCW - bottom to top
2 - 180[degree] CCW - right to left
3 - 270[degree] CCW - top to bottom
(...continued overpage)
- 27 -
pic_draw_text ... continued
The 'justify' argument can take values from 0 to 8
inclusive. This variable determines the orientation
of the text string with respect to the current pen
location. The convention adopted is shown below:
0 - centred vertically : centre
1 - centred vertically : right
2 - centred horizontally : under
3 - centred vertically : left
4 - centred horizontally : above
5 - right : below
6 - left : below
7 - right : above
8 - left : above
RETURN: The pic_draw_text function returns 0 if the
appropriate commands were written to the opened PIC
file. If an error occurred a code indicating the type
of error is returned. Possible error codes are:
2 - file write error
9 - invalid justification
10- invalid rotation angle
- 28 -
8. FUTURE UPDATES
Additional functions are being developed at present to enhance
the PIC_TC package. A summary of these improvements are listed
below:
* Windowing features to mimic the HPGL command IW.
* The circle command is being developed to reflect the
current line type.
* An aspect ratio command to automatically set the
drawing limits.
This update will be sent free of charge to all registered users by
Fall 1990. CSH Services solicitates feedback with regard to this
development and encourages user to define their needs.